home *** CD-ROM | disk | FTP | other *** search
/ PC Active 2009 July/August / PC Active NR.227.iso / Software / Games / windows / Freeciv-2.1.9-win32-gtk2-setup.exe / doc / CodingStyle < prev    next >
Encoding:
Text File  |  2009-03-25  |  7.2 KB  |  236 lines
  1. ===========================================================================
  2.  Freeciv Style Guide
  3. ===========================================================================
  4.  
  5. If you want to hack Freeciv, and want your patches to be accepted, it
  6. helps to follow some simple style rules. Yes, some of these are a bit 
  7. nit-picky, but wars are fought over the silliest things...
  8.  
  9. - Freeciv is programmed in plain C (except the BEOS client). This
  10.   means that C++ features like:
  11.     - C++-style comments (i.e., // comments) and
  12.     - declaration variables in the middle of the function body
  13.   are forbidden.
  14.  
  15. - Use K&R indentation style with indentation 2 (if in doubt, use
  16.   "indent -kr -i2 -l77").  However, do not re-indent areas of code you
  17.   are not modifying or creating. Here are the most important properties:
  18.     - lines are at most 77 chars long
  19.     - spaces are inserted before and after operators (instead of 
  20.       "int a,b,c;" use "int i, j, k;" and instead of "if(foo<=bar) c=a+b;"
  21.       use "if (foo <= bar) c = a + b;" -- note the space between "if" 
  22.       and the bracket)
  23.     - function braces begin and end in the first column.
  24.         int foo()
  25.         {
  26.           return 0;
  27.         }
  28.       instead of
  29.         int foo() {
  30.           return 0;
  31.         }
  32.     - the tab width is 8
  33.     - the indentation is 2 columns per level
  34.  
  35. - An empty line should be placed between two separate blocks of code.
  36.  
  37. - Place operators at the beginning of a line, not at the end.  It should be
  38.     if ((a
  39.          && b)
  40.         || c) {
  41.   instead of
  42.     if ((a &&
  43.          b) ||
  44.         c) {
  45.  
  46. ================================
  47.  Comments
  48. ================================
  49.  
  50. - Every function should have a comment header.  The comment should look 
  51.   like the example below, indented by two spaces.  It should be above the 
  52.   function's implementation, not the prototype:
  53.  
  54. /*************************************************************************
  55.   the description of the function should be here
  56.   any information is helpful, such as who calls this function, etc.
  57.   do _not_ introduce a new function without some sort of comment.
  58. *************************************************************************/
  59. int the_function_starts_here(int value) 
  60. {
  61.   ...
  62. }
  63.  
  64. - One line comments. Comments should be indented correctly and 
  65.   placed above the code being commented upon:
  66.  
  67.   int x;
  68.  
  69.   /* I am a single line comment */
  70.   x = 3;
  71.  
  72. - Multiline comments. Asterisks should be placed in front of the 
  73.   comment line like so:
  74.  
  75.   /* I am a multiline
  76.    * comment, blah 
  77.    * blah blah */
  78.  
  79. - Comments in declarations. If you need to comment a declared variable,
  80.   it should be as such:
  81.  
  82.   struct foo {
  83.     int bar;                    /* bar is used for ....
  84.                                  * in ..... way */
  85.     int blah;                   /* blah is used for .... */
  86.   };
  87.  
  88. - Comments in conditionals. If you need a comment to show program flow,
  89.   it should be below the if or else:
  90.  
  91.   if (is_barbarian(pplayer)) {
  92.     x++;
  93.   } else {
  94.     /* If not barbarian, ... */
  95.     x--;
  96.   }
  97.  
  98. - Comments to translators are stored before the N_(), _() or Q_() marked
  99.   string, and are preceded by "TRANS:".  These comments are copied to the
  100.   translators file.  Use them whenever you think the translators may need
  101.   some more information:
  102.  
  103.     /* TRANS: Don't translate "commandname". */
  104.     printf(_("commandname <arg> [-o <optarg>]"));
  105.  
  106. ================================
  107.  Declaring variables
  108. ================================
  109.  
  110. - Variables can be initialized as soon as they're declared:
  111.  
  112. int foo(struct unit *punit)
  113. {
  114.   int x = punit->x;
  115.   int foo = x;
  116.   char *blah;
  117.  
  118.   ...
  119. }
  120.  
  121. - After variables are declared, there should be an empty line before the
  122.   rest of the function body.
  123.  
  124. - Merging declarations. Variables do not have to be declared one per line;
  125.   however, they should only be grouped by similar function.
  126.  
  127. int foo(struct city *pcity)
  128. {
  129.   int i, j, k;
  130.   int total, cost;
  131.   int build = pcity->shield_stock;
  132. }
  133.  
  134. ================================
  135.  Bracing
  136. ================================
  137.  
  138. - Extra braces on iterates. Note that the *_iterate_end; should be placed 
  139.   on the same line as the end brace:
  140.  
  141.   unit_list_iterate(pcity->units_supported, punit) {
  142.     kill(punit);
  143.   } unit_list_iterate_end;
  144.  
  145. - In switch statements, braces should only be placed where needed, i.e. to
  146.   protect local variables.
  147.  
  148. - Braces shall be used after conditionals:
  149.  
  150.   if (x == 3) {
  151.     return;
  152.   }
  153.  
  154.  and 
  155.  
  156.   if (x == 3) {
  157.     return 1;
  158.   } else {
  159.     return 0;
  160.   }
  161.  
  162.  not
  163.  
  164.   if (x == 3)
  165.     return 1;  /* BAD! */
  166.  
  167. ================================
  168.  Other stuff
  169. ================================
  170.  
  171. - If an empty block is needed you should put an explanatory comment in
  172.   an empty block (i.e. {}):
  173.  
  174.   while (*i++) {
  175.     /* nothing */
  176.   }
  177.  
  178. - Use the postfix operator instead of the prefix operator when either will
  179.   work.  That is, write "a++" instead of "++a".
  180.  
  181. - Order include files consistently: All includes are grouped
  182.   together. These groups are divided by an empty line. The order of
  183.   these groups are as follow:
  184.  
  185.     1) config.h (see below)
  186.     2) system include files which are OS-independent (part of
  187.        C-standard or POSIX)
  188.     3) system include files which are OS-dependent or conditional
  189.        includes
  190.     4) include files from common/ and common/aicore
  191.     5) include files from client/, client/include and client/agents
  192.     6) include files from client/gui-*
  193.     7) include files from server/
  194.     8) include files from ai/
  195.  
  196.   Each group is sorted in alphabetic order. This helps to avoid adding
  197.   unnecessary or duplicated include files.
  198.  
  199.   It is very important that '#include <config.h>' be included at the top of
  200.   every .c file (it need not be included from .h files).  Some definitions in
  201.   config.h will affect how the code is compiled, without which you can end
  202.   up with bad and untraceable memory bugs.
  203.  
  204. - If you use a system specific feature, don't add #ifdef __CRAY__ or
  205.   something like that.  Rather write a check for that feature for
  206.   both configure.in and configure.ac, and use a meaningful macro name 
  207.   in the source.
  208.  
  209. - Always prototype global functions in the appropriate header file.
  210.   Local functions should always be declared as static. To catch these
  211.   and some other problems please use the following warning options
  212.   "-Wall -Wpointer-arith -Wcast-align -Wmissing-prototypes
  213.   -Wmissing-declarations -Wstrict-prototypes -Wnested-externs" if you
  214.   use gcc.
  215.  
  216. - Header files should be compatible with C++ but code (.c) files need not
  217.   be.  This means some C++ keywords (like "this" or "class") may not be
  218.   used in header files.  It also means casts on void pointers (which should
  219.   be avoided in C files) must be used in headers.
  220.  
  221. - If you send patches, use "diff -u" (or "diff -r -u"). "svn diff" works
  222.   correctly without extra parameters.
  223.   For further information, see
  224.   <http://www.freeciv.org/index.php/How_to_Contribute>.
  225.   Also, name patch files descriptively (e.g. "fix-foo-bug-0.diff" is good,
  226.   but "freeciv.diff" is not).
  227.  
  228. - When doing a "diff" for a patch, be sure to exclude unnecessary files
  229.   by using the "-X" argument to "diff".  E.g.:
  230.  
  231.     % diff -ruN -Xdiff_ignore freeciv_svn freeciv >/tmp/fix-foo-bug-0.diff
  232.  
  233.   A suggested "diff_ignore" file is included in the Freeciv distribution.
  234.  
  235. ===========================================================================
  236.